Cryptocurrency Subscriptions URI 

Informal Protocol Specification 
Document Description 

This document is an informal specification meant to be readable by the community. Once more wallets 
implement the protocol, a more detailed specification can be written which will be approved by 
standardization groups (bip/rfc/etc) 

Protocol Overview 

This is a protocol for enabling payment subscriptions within the cryptocurrency ecosystem. The 
protocol exist completely between merchants and wallet applications. No change to the transaction 
network is needed to implement this specification. For this reason, this specification is not currency 
specific, meaning it can apply to Bitcoin wallets, as well as Dogecoin wallets and Litecoin wallets. 

Basic Description 

First, the user signs up for the service on the merchant's website. At the end of the process, instead of 
the user sending bitcoin directly to the merchant's address, the user configures their wallet to send 
money to merchant on a weekly/monthy/daily basis. 

Example from the user's perspective: 

Bob goes to magazine.com, adds a magazine subscription to his cart. At the end of the checkout 
process, Bob sees this: 

Thank you for your subscription! You now must click here to configure your bitcoin wallet 
to send us payment at the start of each month. 

The bolded part is a link with the following address: 

paymentsubscription:/ /magazine.com/payment?token=wifhvwgrj568tbku 

Given that Bob is using a wallet application with this protocol supported, when he clicks the link, 
his wallet application is opened with a popup form that looks like this: 



Create New subscription 



name: magazine subscription 



max payment amount: 24000 bits (optional) 



first payment amount: 24000 bits 



schedule: 



monthly 



uri: magazine.com/payment?token=wifhvwgrj568tbku 



end date: 



(optional) 



send me notification via email after each payment [ ]yes [x]no 
request my approval before each payment? [ ]yes [x]no 
[submit] 

The form is already prefilled with information much like how email clients fill in "subject" and 
"to" fields on the "new message dialog" when clicking on "mailto:" links. 

When Bob clicks the submit button, his wallet is now configured, and he can now expect to 
receive magazines in the mail. 



The payment uri is basically what developers call a "callback". It is a url that returns a JSON document 
containing all the information needed to get the subscription going. An example return value is as 



{"address": "lHWpyFJ7N6rvFkq3ZCMiFnqM6hviNFmG5X", "amount": 24000, 
"units": "bits", "currency": "BTC", "schedule": "0 01 **"} 

In the example above, there is a 'token' parameter in the url. This bit of information corresponds 
to Bob's user account on magazine.com. This parameter is here for illustrative purposes only, and 
not part of the protocol. The callback URL can be any valid URL. 

Wallet applications on some platforms may not have access to a cron like utility, so some wallets 
will have a tough time supporting this protocol. 

The url should be idempotent. The wallet may call it multiple times throughout the whole 
process. 



This value determines how often the wallet should send payment. The syntax for this section comes 
straight from the cron utility. In the example above, the value "0 0 1 * *" means "at midnight on the 
first of each month". 



Technical Details 



follows: 



Schedule 



The times at which the schedule value describes is the time at which the user's wallet sends the 



payment. From the merchant's perspective, the payment may be due at a later date. For instance, the 
magazine subscription defines the payment be sent on midnight on the first of each month, but in 
reality the merchant won't expect the payment until a few hours or days after that time. This is to 
account for situations where the user has to respond to the authorize request (if there is one). Also, 
some users may have their computer's timezone set in such a way that the payment arrives a few hours 
later than expected. 

Canceling 

If the user wants to end the subscription, all they have to do is delete the subscription from their wallet 
application. Eventually the merchant will discover the customer is not paying any more and the 
customer's service will be canceled. The merchant can also cancel the subscription by making it so their 
callback always returns an amount of 0. 

Interface 

Each wallet application is responsible for making the user experience enjoyable. For instance, the 
wallet could send an email to the user asking to authorize the payment before making any payment. Or 
the wallet could only send an authorize email if the amount is greater than a user-defined limit. 

Making it easy for the user 

To make the data entry process easier, the merchant can construct a link element on their page that, 
when clicked by the user, automatically enters the data to the user's bitcoin wallet. For example: 

<a href= "paymentsubscription: //magazine.com/payment? 
token=wifhvwgrj568tbku " > Click here to subscribe !</a> 

Another way to make it easy is to encode the subscription into a QR code. The value to encode 
will look like this: 

paymentsubscription: //magazinexom/payment?token=wifhvwgrj568tbku 

When wallet applications see this QR code, they will know that this is a subscription, and will 
handle setting it up automatically. 

Problems with this spec 

• The "paymentsubscription:" link syntax is not currently supported in any browser. This is a 
chicken and egg problem. 

• Not bitcoin specific. A lot of people in the bitcoin community hate altcoins. The fact that this 
protocol makes it easy to do subscriptions with other currencies may cause friction. 



Feedback 

Add a comment to whatever source you got this document (reddit/hacker news/bitcointalk/etc) 



